/*-------------------------------------------------------------------------
 *
 * selfuncs.h
 *	  标准运算符的选择性函数，以及选择性和成本估算的杂项基础设施。
 *
 *
 * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/utils/selfuncs.h
 *
 *-------------------------------------------------------------------------
 */
#ifndef SELFUNCS_H
#define SELFUNCS_H

#include "access/htup.h"
#include "fmgr.h"
#include "nodes/pathnodes.h"


/*
 * 注意：默认的选择性估计并不是完全随机选择的。
 * 我们希望它们足够小，以确保在典型的表密度约为 ~100 元组/页时能使用索引扫描。
 * 因此，例如，0.01 还不够小，因为这使得几乎所有页面似乎都会被命中。
 * 此外，由于我们有时将 eqsel 估计为 1/num_distinct，我们可能希望 DEFAULT_NUM_DISTINCT 等于
 * 1/DEFAULT_EQ_SEL。
 */

/* 等式的默认选择性估计，例如 "A = b" */
#define DEFAULT_EQ_SEL	0.005

/* 不等式的默认选择性估计，例如 "A < b" */
#define DEFAULT_INEQ_SEL  0.3333333333333333

/* 范围不等式的默认选择性估计 "A > b AND A < c" */
#define DEFAULT_RANGE_INEQ_SEL	0.005

/* 多范围不等式的默认选择性估计 "A > b AND A < c" */
#define DEFAULT_MULTIRANGE_INEQ_SEL	0.005

/* 模式匹配运算符的默认选择性估计，例如 LIKE */
#define DEFAULT_MATCH_SEL	0.005

/* 其他匹配运算符的默认选择性估计 */
#define DEFAULT_MATCHING_SEL	0.010

/* 表中不同值的默认数量 */
#define DEFAULT_NUM_DISTINCT  200

/* 布尔和空值测试节点的默认选择性估计 */
#define DEFAULT_UNK_SEL			0.005
#define DEFAULT_NOT_UNK_SEL		(1.0 - DEFAULT_UNK_SEL)


/*
 * 将计算的概率估计（可能因为四舍五入或
 * 估计误差而受影响）限制在有效范围内。参数必须是浮点变量。
 */
#define CLAMP_PROBABILITY(p) \
	do { \
		if (p < 0.0) \
			p = 0.0; \
		else if (p > 1.0) \
			p = 1.0; \
	} while (0)

/*
 * 一组标志，某些选择性估计函数可以返回给调用者，以提供有关在
 * 估计过程中所做的一些假设的进一步详细信息。
 */
#define SELFLAG_USED_DEFAULT		(1 << 0)	/* 估计回退到
												 * 上述定义的一个 DEFAULT。 */

typedef struct EstimationInfo
{
	uint32		flags;			/* 标志，如上所述，用于标记估计的特殊
								 * 属性。 */
} EstimationInfo;

/* 从 examine_variable 和相关函数返回数据 */
typedef struct VariableStatData
{
	Node	   *var;			/* Var 或表达式树 */
	RelOptInfo *rel;			/* 关系，如果无法识别则为 NULL */
	HeapTuple	statsTuple;		/* pg_statistic 元组，如果没有则为 NULL */
	/* 注意：如果 statsTuple!=NULL，当调用者完成时必须释放 */
	void		(*freefunc) (HeapTuple tuple);	/* 如何释放 statsTuple */
	Oid			vartype;		/* 表达式的暴露类型 */
	Oid			atttype;		/* 实际类型（去掉重标记后） */
	int32		atttypmod;		/* 实际 typmod（去掉重标记后） */
	bool		isunique;		/* 匹配唯一索引或 DISTINCT 子句 */
	bool		acl_ok;			/* 对表或列的 ACL 检查结果 */
} VariableStatData;

#define ReleaseVariableStats(vardata)  \
	do { \
		if (HeapTupleIsValid((vardata).statsTuple)) \
			(vardata).freefunc((vardata).statsTuple); \
	} while(0)


/*
 * genericcostestimate 是一个通用估计器，可用于
 * 大多数索引类型。在某些情况下，我们将 genericcostestimate 用作基础
 * 代码，然后在类型特定调用函数中包含额外的索引类型特定知识。
 * 为了避免代码重复，我们使 genericcostestimate 返回多个中间值，以及
 * 其初步的输出成本值估计。GenericCosts 结构包含所有这些值。
 *
 * 调用者应将 GenericCosts 的所有字段初始化为零。此外，
 * 如果他们对估计访问的叶索引元组的数量有比默认值更好的方法，可以将 numIndexTuples 设置为某个正值。
 */
typedef struct
{
	/* 这些是成本估算器必须返回给规划者的值 */
	Cost		indexStartupCost;	/* 与索引相关的启动成本 */
	Cost		indexTotalCost; /* 与索引相关的总扫描成本 */
	Selectivity indexSelectivity;	/* 索引的选择性 */
	double		indexCorrelation;	/* 索引的顺序相关性 */

	/* 我们沿途获得的中间值 */
	double		numIndexPages;	/* 访问的叶子页面数量 */
	double		numIndexTuples; /* 访问的叶子元组数量 */
	double		spc_random_page_cost;	/* 相关的 random_page_cost 值 */
	double		num_sa_scans;	/* 来自 ScalarArrayOpExprs 的索引扫描数量 */
} GenericCosts;

/* 插件的钩子，在我们请求统计信息时获取控制权 */
typedef bool (*get_relation_stats_hook_type) (PlannerInfo *root,
											  RangeTblEntry *rte,
											  AttrNumber attnum,
											  VariableStatData *vardata);
extern PGDLLIMPORT get_relation_stats_hook_type get_relation_stats_hook;
typedef bool (*get_index_stats_hook_type) (PlannerInfo *root,
										   Oid indexOid,
										   AttrNumber indexattnum,
										   VariableStatData *vardata);
extern PGDLLIMPORT get_index_stats_hook_type get_index_stats_hook;

/* selfuncs.c 中的函数 */

extern void examine_variable(PlannerInfo *root, Node *node, int varRelid,
							 VariableStatData *vardata);
extern bool statistic_proc_security_check(VariableStatData *vardata, Oid func_oid);
extern bool get_restriction_variable(PlannerInfo *root, List *args,
									 int varRelid,
									 VariableStatData *vardata, Node **other,
									 bool *varonleft);
extern void get_join_variables(PlannerInfo *root, List *args,
							   SpecialJoinInfo *sjinfo,
							   VariableStatData *vardata1,
							   VariableStatData *vardata2,
							   bool *join_is_reversed);
extern double get_variable_numdistinct(VariableStatData *vardata,
									   bool *isdefault);
extern double mcv_selectivity(VariableStatData *vardata,
							  FmgrInfo *opproc, Oid collation,
							  Datum constval, bool varonleft,
							  double *sumcommonp);
extern double histogram_selectivity(VariableStatData *vardata,
									FmgrInfo *opproc, Oid collation,
									Datum constval, bool varonleft,
									int min_hist_size, int n_skip,
									int *hist_size);
extern double generic_restriction_selectivity(PlannerInfo *root,
											  Oid oproid, Oid collation,
											  List *args, int varRelid,
											  double default_selectivity);
extern double ineq_histogram_selectivity(PlannerInfo *root,
										 VariableStatData *vardata,
										 Oid opoid, FmgrInfo *opproc,
										 bool isgt, bool iseq,
										 Oid collation,
										 Datum constval, Oid consttype);
extern double var_eq_const(VariableStatData *vardata,
						   Oid oproid, Oid collation,
						   Datum constval, bool constisnull,
						   bool varonleft, bool negate);
extern double var_eq_non_const(VariableStatData *vardata,
							   Oid oproid, Oid collation,
							   Node *other,
							   bool varonleft, bool negate);

extern Selectivity boolvarsel(PlannerInfo *root, Node *arg, int varRelid);
extern Selectivity booltestsel(PlannerInfo *root, BoolTestType booltesttype,
							   Node *arg, int varRelid,
							   JoinType jointype, SpecialJoinInfo *sjinfo);
extern Selectivity nulltestsel(PlannerInfo *root, NullTestType nulltesttype,
							   Node *arg, int varRelid,
							   JoinType jointype, SpecialJoinInfo *sjinfo);
extern Selectivity scalararraysel(PlannerInfo *root,
								  ScalarArrayOpExpr *clause,
								  bool is_join_clause,
								  int varRelid, JoinType jointype, SpecialJoinInfo *sjinfo);
extern int	estimate_array_length(Node *arrayexpr);
extern Selectivity rowcomparesel(PlannerInfo *root,
								 RowCompareExpr *clause,
								 int varRelid, JoinType jointype, SpecialJoinInfo *sjinfo);

extern void mergejoinscansel(PlannerInfo *root, Node *clause,
							 Oid opfamily, int strategy, bool nulls_first,
							 Selectivity *leftstart, Selectivity *leftend,
							 Selectivity *rightstart, Selectivity *rightend);

extern double estimate_num_groups(PlannerInfo *root, List *groupExprs,
								  double input_rows, List **pgset,
								  EstimationInfo *estinfo);

extern void estimate_hash_bucket_stats(PlannerInfo *root,
									   Node *hashkey, double nbuckets,
									   Selectivity *mcv_freq,
									   Selectivity *bucketsize_frac);
extern double estimate_hashagg_tablesize(PlannerInfo *root, Path *path,
										 const AggClauseCosts *agg_costs,
										 double dNumGroups);

extern List *get_quals_from_indexclauses(List *indexclauses);
extern Cost index_other_operands_eval_cost(PlannerInfo *root,
										   List *indexquals);
extern List *add_predicate_to_index_quals(IndexOptInfo *index,
										  List *indexQuals);
extern void genericcostestimate(PlannerInfo *root, IndexPath *path,
								double loop_count,
								GenericCosts *costs);

/* 在 array_selfuncs.c 中的函数 */

extern Selectivity scalararraysel_containment(PlannerInfo *root,
											  Node *leftop, Node *rightop,
											  Oid elemtype, bool isEquality, bool useOr,
											  int varRelid);

#endif							/* SELFUNCS_H */
